package com.sms.service;

import com.sms.exception.DataFileCorruptedException;
import com.sms.exception.SMSException;
import com.sms.model.Score;

import java.util.List;

/**
 * 成绩管理服务接口
 * 位置：com.sms.service.ScoreService
 */
public interface ScoreService {
    /**
     * 添加成绩记录
     * @param score 成绩对象
     * @throws SMSException 当成绩已存在或数据无效时抛出
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    void addScore(Score score) throws SMSException, DataFileCorruptedException;
    
    /**
     * 更新成绩信息
     * @param studentId 学号
     * @param courseId 课程ID
     * @param newScore 新成绩
     * @return true-更新成功, false-成绩记录不存在
     * @throws SMSException 当成绩无效时抛出
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    boolean updateScore(String studentId, String courseId, double newScore) throws SMSException, DataFileCorruptedException;
    
    /**
     * 删除成绩记录
     * @param studentId 学号
     * @param courseId 课程ID
     * @return true-删除成功, false-成绩记录不存在
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    boolean deleteScore(String studentId, String courseId) throws DataFileCorruptedException;
    
    /**
     * 根据学号和课程ID查询成绩
     * @param studentId 学号
     * @param courseId 课程ID
     * @return 成绩对象，未找到时返回null
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    Score getScore(String studentId, String courseId) throws DataFileCorruptedException;
    
    /**
     * 根据学号查询该学生的所有成绩
     * @param studentId 学号
     * @return 成绩列表（按课程ID排序）
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    List<Score> getScoresByStudent(String studentId) throws DataFileCorruptedException;
    
    /**
     * 根据课程ID查询该课程的所有成绩
     * @param courseId 课程ID
     * @return 成绩列表（按学号排序）
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    List<Score> getScoresByCourse(String courseId) throws DataFileCorruptedException;
    
    /**
     * 获取所有成绩记录
     * @return 成绩列表
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    List<Score> getAllScores() throws DataFileCorruptedException;
    
    /**
     * 计算学生平均分
     * @param studentId 学号
     * @return 平均分（保留2位小数）
     * @throws SMSException 当学生不存在或没有成绩时抛出
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    double calculateStudentAverage(String studentId) throws SMSException, DataFileCorruptedException;
    
    /**
     * 计算课程平均分
     * @param courseId 课程ID
     * @return 平均分（保留2位小数）
     * @throws SMSException 当课程不存在或没有成绩时抛出
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    double calculateCourseAverage(String courseId) throws SMSException, DataFileCorruptedException;
    
    /**
     * 获取课程成绩前N名的学生
     * @param n 前N名
     * @param courseId 课程ID
     * @return 成绩列表（按成绩降序排列）
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    List<Score> getTopNStudents(int n, String courseId) throws DataFileCorruptedException;
}